Skip to main content

Run Functions

Use this adapter to manage model runs.

Importing the adapter​

To use the functions of the Run adapter, import it as shown:
import { runAdapter } from 'epicenter-libs';

The runAdapter namespace exports functions that make calls to the Run API.

learn more

For descriptions of the objects used by the Run adapter functions, read Run entities.

Create​

Create run​

Call the create() function to create a run.

By default, all runs are created with the user's ID (userKey), except in the case of world-scoped runs.

If no permit is specified, Epicenter will assign a default determined by the session user type and the scope boundary. For a participant creating a run, the default readLock/writeLock is USER/USER, unless that run is scoped to a world, in which case PARTICIPANT/FACILITATOR is the default. Admins and facilitators/reviewers have their own defaults.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a POST request to the /run endpoint.
  • Creates a new run using the specified model and scope parameters.
  • Optionally includes execution context, model context, permissions, and routing options.
  • Returns a Run object representing the newly created run.
Function signature
export async function create(
    model: string,
    scope: { userKey?: string } & GenericScope,
    optionals: RunCreateOptions = {},
): Promise<Run>
Parameters​
Return value​

A promise resolving to a Run object containing details of the newly created run.

Usage example​
import { runAdapter, SCOPE_BOUNDARY } from 'epicenter-libs';

runAdapter.create('model.py', {
     scopeBoundary: SCOPE_BOUNDARY.GROUP,
     scopeKey: '0000017dd3bf540e5ada5b1e058f08f20461'
    });

Clone run​

The clone() function clones an existing run instance based on the provided runKey.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a POST request to the /run/clone/{runKey} endpoint.
  • Clones an existing run identified by the provided run key, optionally modifying context or tracking information.
  • Returns a Run object representing the newly cloned run.
Function signature
export async function clone(
    runKey: string,
    optionals: {
        ephemeral?: boolean,
        trackingKey?: string,
        modelContext?: ModelContext,
        executionContext?: ExecutionContext,
    } & RoutingOptions = {}
): Promise<Run>

Parameters​

  • runKey: string - The run key of the run to be cloned.
  • optionals: {} - (Optional) Additional options for cloning the run:
    • ephemeral?: boolean - (Optional) If true, the run will only exist so long as its in memory. Nothing is written to the database, history, or variables.
    • trackingKey?: string - (Optional) A string that you can assign to a run as a marker. You can perform a search for runs that have a specific trackingKey.
    • modelContext?: ModelContext - (Optional) Model context file overrides. Not tracked by clone operations.
    • executionContext?: ExecutionContext - (Optional) Carries arguments for model file worker on model initialization. This is tracked by clone operations.
    • RoutingOptions - Additional routing options for request handling.

Return value​

A promise resolving to a Run object containing details of the newly cloned run.

Retrieve​

Use these methods to query the Epicenter API for runs.

Retrieve run​

The get() function retrieves a run by the run key.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a GET request to the endpoint /run/{runKey}.
  • Retrieves a run object based on the specified run key.
  • Returns a Run object containing the run's details.
Function signature
export async function get(
    runKey: string,
    optionals: RoutingOptions = {}
): Promise<Run>

Parameters​

  • runKey (string): The unique key identifying the run to retrieve.
  • optionals (Type: RoutingOptions = {}): Additional routing options.

Return value​

A promise that resolves to a Run object representing the requested run.

Usage example​

import { runAdapter } from 'epicenter-libs';

const run = await runAdapter.get('0000018d61f1217b22ce0ae605ff00649d6i');

Start run for world​

The retrieveFromWorld() function returns the run associated with the given world key. If the world's run key is null, the function creates a new run and assigns the new run key to the world.

The run gets started and loaded into memory.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a POST request to the endpoint /run/world/{worldKey}.
  • Initiates a run using a provided model file and optional execution/model context.
  • Optionally applies permission locks, ephemeral state, and notification support.
  • Returns the newly initiated Run object.
Function signature
export async function retrieveFromWorld(
    worldKey: string,
    model: string,
    optionals: {
        readLock?: keyof typeof ROLE,
        writeLock?: keyof typeof ROLE,
        ephemeral?: boolean,
        trackingKey?: string,
        modelContext?: ModelContext,
        executionContext?: ExecutionContext,
        allowChannel?: boolean,
    } & RoutingOptions = {}
): Promise<Run>

Parameters​

  • worldKey (string): The key identifying the world to retrieve the run for.
  • model (string): The name of the model file.
  • optionals (Object): Optional parameters:
    • readLock?: keyof typeof ROLE - (Optional) Read lock level. Part of the permit for the run.
    • writeLock?: keyof typeof ROLE - (Optional) Write lock level. Part of the permit for the run.
    • ephemeral?: boolean - (Optional) If true, the run will only exist so long as its in memory. Nothing is written to the database, history, or variables.
    • trackingKey?: string - (Optional) A string that you can assign to a run as a marker. You can perform a search for runs that have a specific trackingKey.
    • modelContext?: ModelContext - (Optional) Model context file overrides. Not tracked by clone operations.
    • executionContext?: ExecutionContext - (Optional) Carries arguments for model file worker on model initialization. This is tracked by clone operations.
    • allowChannel?: boolean - (Optional) Opt into push notifications. Applicable to projects with phylogeny >= SILENT.
    • RoutingOptions - Additional routing options for request handling.

Return value​

A promise that resolves to a Run object.

Usage example​

import { runAdapter } from 'epicenter-libs';

const run = await runAdapter.retrieveFromWorld('0000017a445032dc38cb2cecd5fc13708314', 'model.py');

Get run using strategy​

The getWithStrategy() function fetches an existing run or creates a new one, depending on the strategy provided.

tip

Provide a value for the strategy param using the RunStrategy enum.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Determines whether to fetch the run or create a new one according to the strategy argument provided.
  • Returns a single Run object.
Function signature
export async function getWithStrategy(
    strategy: RunStrategy,
    model: string,
    scope: GenericScope,
    optionals: RunCreateOptions = {}
): Promise<Run>

Parameters​

  • strategy (RunStrategy): Determines the strategy to use.
  • model (string): The name of your model file.
  • scope (GenericScope): The scope associated of the run.
  • optionals (Type: RunCreateOptions = {}): Additional options for run creation. May include execution context, model context, ephemeral flag, and other routing options.

Return value​

A promise that resolves to the retrieved or newly created Run object.

Usage example​


import { runAdapter } from 'epicenter-libs';
runAdapter.getWithStrategy(
    'reuse-across-sessions',
    'model.py',
    {
        scopeBoundary: SCOPE_BOUNDARY.GROUP,
        scopeKey: '123456789',
    },
);

Filtered query​

To search for runs within a group or an episode, or for runs with a specific scope, call the query() function.

Important

This function loads model variables only from archived state. It does not restore runs to memory.

tip

When searching within a group, set the includeEpisodes parameter to true to include runs tied to specific episodes.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a GET request to the endpoint /run/in/{groupName}/{episodeName}/{modelFile}, /run/in/{groupName}/{modelFile}, or /run/{scopeBoundary}/{scopeKey}/{modelFile} if the scope param is provided.
  • Queries existing runs that match the filters, scope, group, and variable/metadata conditions specified in the searchOptions parameter.
  • Returns a paginated list of Run objects that match the search criteria.
Function signature
export async function query(
    model: string,
    searchOptions: {
        timeout?: number,
        variables?: string[],
        metadata?: string[],
        scope?: { userKey?: string } & GenericScope,
        groupName?: string,
        episodeName?: string,
        includeEpisodes?: boolean,
    } & GenericSearchOptions,
    optionals: RoutingOptions = {}
): Promise<Page<Run>>

Parameters​

  • model: string - The name of your model file.
  • searchOptions: object - Search options:
    • timeout?: number - (Optional) Number of seconds to wait for the response from the server.
    • variables?: string[] - (Optional) List of variables to include with the runs found.
    • metadata?: string[] - (Optional) List of metadata to include with the runs found.
    • scope?: { userKey?: string } & GenericScope - (Optional) Scope of the run. Can consist of GenericScope plus a userKey for user specific scope.
    • groupName?: string - (Optional) Search for runs within this group.
    • episodeName?: string - (Optional) Search for runs within this episode.
    • includeEpisodes?: boolean - (Optional) When searching within a group, include runs tied to specific episodes. The default is false.
    • GenericSearchOptions - Additional search options that include filter and sort conditions.
  • optionals:

Return value​

A Promise resolving to a paginated list of Run objects.

Usage example​

import { runAdapter } from 'epicenter-libs';
runAdapter.query('model.xlsx', {
    filter: [
        'var.foo|=1|2|3',             // look for runs with a variable 'foo' with the values 1, 2, or 3
        'var.score>=90',              // looks for runs with a variable 'score' higher than or equal to 90
        'var.certified*=true'         // looks for runs where the variable 'certified' exists,
        'run.hidden=false',           // where the run's 'hidden' attribute is false
        'meta.classification~=bar-*'  // where the run metadata contains a 'classification' that begins with 'bar-',
        'meta.categorization~=*-baz'  // where the run metadata contains a 'categorization' that does not end with '-baz',
    ],
    sort: ['+run.created']            // sort all findings by the 'created' field (ascending)
    variables: ['foo', 'baz'],        // include the run variables for 'foo' and 'baz' in the response
    metadata: ['classification']      // include the run metadata for 'classification' in the response
});

Update​

Update run​

Update a run.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The update() function:

  • Constructs a PATCH request to the endpoint /run/{runKey}.
  • Updates the properties of the run identified by the runKey param.
  • Returns the updated run.
Function signature
export async function update(
    runKey: string,
    update: {
        readLock?: keyof typeof ROLE,
        writeLock?: keyof typeof ROLE,
        trackingKey?: string,
        marked?: boolean,
        hidden?: boolean,
        closed?: boolean,
        allowChannel?: boolean,
    },
    optionals: RoutingOptions = {}
): Promise<Run>

Parameters​

  • runKey (string): The key identifying the run to be updated. Can support an array of keys in internal logic.
  • update (Type: { readLock?: keyof typeof ROLE, writeLock?: keyof typeof ROLE, trackingKey?: string, marked?: boolean, hidden?: boolean, closed?: boolean, allowChannel?: boolean }): Object containing run attributes to update.
    • readLock?: keyof typeof ROLE - (Optional) Read lock level. Part of the permit for the run.
    • writeLock?: keyof typeof ROLE - (Optional) Write lock level. Part of the permit for the run.
    • trackingKey (string): (Optional) A string that you can assign to a run as a marker. You can perform a search for runs that have a specific trackingKey.
    • marked (boolean): Equivalent to the "saved" flag in v2.
    • hidden (boolean): Equivalent to the "trashed" flag in v2.
    • closed (boolean): Marks the run as closed, meaning it will not be restored again.
    • allowChannel (boolean): Opt into push notifications. Applies to projects with phylogeny >= SILENT.
  • optionals (Type: RoutingOptions = {}): Additional routing options.

Return value​

A promise that resolves to the updated Run object.

Usage example​

import { runAdapter } from 'epicenter-libs';

await runAdapter.update('0000018d61f1217b22ce0ae605ff00649d6i', {
    marked: true,
    hidden: false
});

Manage​

Restore run​

Start up an existing run and load it into memory. Restore the run state by replaying all the state changing operations from the run's history.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The restore() function:

  • Constructs a POST request to the endpoint /run/restore/{runKey}.
  • Restores a previously saved run, optionally in an ephemeral mode.
  • Allows setting model and execution context during restoration.
  • Returns the restored Run object.
Function signature
export async function restore(
    runKey: string,
    optionals: {
        ephemeral?: boolean,
        modelContext?: ModelContext,
        executionContext?: ExecutionContext,
    } & RoutingOptions = {}
): Promise<Run>

Parameters​

  • runKey (string): The run key of the run to restore.
  • optionals (Type: { ephemeral?: boolean, modelContext?: ModelContext, executionContext?: ExecutionContext } & RoutingOptions):

Return value​

A promise that resolves to the restored Run object.

Usage example​

import { runAdapter } from 'epicenter-libs';

const restoredRun = await runAdapter.restore('0000018d61f1217b22ce0ae605ff00649d6i');

Rewind run​

The rewind() function stops the run, re-starts it, and replays it to a specified point.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a POST request to the endpoint /run/rewind/{runKey}.
  • Returns the updated Run object after rewind.
Function signature
export async function rewind(
    runKey: string,
    steps: number,
    optionals: {
        ephemeral?: boolean,
        modelContext?: ModelContext,
    } & RoutingOptions = {}
): Promise<Run>

Parameters​

  • runKey (string): The run key identifying the run to rewind.
  • steps (number): The number of steps to rewind the run.
  • optionals (Type: { ephemeral?: boolean, modelContext?: ModelContext } & RoutingOptions):
    • ephemeral?: boolean - (Optional) If true, the run will only exist so long as its in memory. Nothing is written to the database, history, or variables.
    • modelContext?: ModelContext - (Optional) Model context file overrides. Not tracked by clone operations.
    • RoutingOptions: Additional routing options.

Return value​

A promise that resolves to the rewound Run object.

Usage example​

import { runAdapter } from 'epicenter-libs';

const rewoundRun = await runAdapter.rewind('0000018d61f1217b22ce0ae605ff00649d6i', 5, {ephemeral: true });

Migrate run​

The migrate() function copies a run to a different episode.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

  • Constructs a POST request to the /run/migrate/to/{episodeKey}/{runKey} endpoint using the provided parameters.
  • Sends the API request.
  • Returns a the new run.
Function signature
export async function migrate(
    runKey: string,
    episodeKey: string,
    optionals: {
        ephemeral?: boolean,
        trackingKey?: string,
        modelContext?: ModelContext,
        executionContext?: ExecutionContext,
    } & RoutingOptions = {}
): Promise<Run>

Parameters​

  • runKey (string): The run key for the run you want to copy and migrate.
  • episodeKey (string): The key of the episode to which the run is being migrated.
  • optionals: Optional parameters that can include:
    • ephemeral (boolean) - If true, the run will only exist so long as its in memory. Nothing is written to the database, history, or variables.
    • trackingKey (string) - A string that you can assign to a run as a marker. You can perform a search for runs that have a specific trackingKey.
    • modelContext (ModelContext) - Model context file overrides. Not tracked by clone operations.
    • executionContext (ExecutionContext) - Carries arguments for model file worker on model initialization. This is tracked by migrate operations.
    • RoutingOptions: Additional routing options.

Return value​

A promise that resolves to the new Run object.

Usage example​

import { runAdapter } from 'epicenter-libs';

const migratedRun = await runAdapter.migrate('abc123', 'episode456', {
    trackingKey: 'track789',
    ephemeral: true,
    modelContext: { param1: 'value1' },
    executionContext: { run: true },
});

Delete​

Delete run​

The remove() function does not actually delete the run. The run is instead removed from memory. The function can be used as a means of preserving server CPUs, and should be used when you do not expect to perform any additional actions that would bring the run back into memory.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a DELETE request to the endpoint /run/{runKey}.
  • Sends the runKey as part of the request URL.
  • Executes the request and returns a void promise upon success.
Function signature
export async function remove(
    runKey: string,
    optionals: RoutingOptions = {}
): Promise<void>

Parameters​

  • runKey (string): The run key identifying the run to be deleted.
  • optionals (Type: RoutingOptions = {}): Additional routing options.

Return value​

A promise that resolves to void when the run is successfully deleted.

Usage example​

import { runAdapter } from 'epicenter-libs';  

runAdapter.remove('0000017a445032dc38cb2cecd5fc13563218');

Delete run for world​

The removeFromWorld() function closes the run and removes it from memory. It also sets the runKey in the specified world to null.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Sends a DELETE request to the /run/world/{worldKey} endpoint.
  • Returns a void promise upon successful deletion.
Function signature
export async function removeFromWorld(
    worldKey: string,
    optionals: RoutingOptions = {},
): Promise<void>

Parameters​

Return value​

A promise that resolves to void when successful.

Usage example​

import { runAdapter } from 'epicenter-libs';

await runAdapter.removeFromWorld('0000017a445032dc38cb2cecd5fc13765987');

Singular runs​

Create singular run​

The createSingular() function creates a singular run, if one does not yet exist.

If a singular run already exists in the project, the function returns the existing one.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a POST request to the endpoint /run/singular based on optional parameters.
  • Returns a Run object representing the created singular run.
Function signature
export async function createSingular(
    model: string,
    optionals: RunCreateOptions = {},
): Promise<Run>

Parameters​

Return value​

A promise resolving to a Run object containing details of the newly created run.

Usage example​

import { runAdapter } from 'epicenter-libs';

runAdapter.createSingular('model.py');

Get singular run key​

The getSingularRunKey() returns the unique runKey for the project's singular run.

Function signature
export async function getSingularRunKey(
    optionals: RoutingOptions = {}
): Promise<number>

Permissions​

Requires a role of ANONYMOUS or higher.

Parameters​

Return value​

  • Type: Promise<number>
  • Description: A promise resolving to the singular run key.

Usage example​

import { runAdapter } from 'epicenter-libs';

runAdapter.getSingularRunKey();

Variables​

Get variables from a run​

The getVariables() function retrieves the current values of specified variables from one or more runs.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a POST request to the /run/variable/{runKey} endpoint.
  • Supports fetching variable values for a single run or an array of runs.
  • Accepts optional execution parameters and request customizations.
  • Returns a mapping of variable names to their current values.
Function signature
export async function getVariables(
    runKey: string | string[],
    variables: string[],
    optionals: {
        timeout?: number,
        ritual?: keyof typeof RITUAL,
        ignorable?: boolean,
    } & RoutingOptions = {}
): Promise<Record<string, unknown> | Record<string, unknown>[]>

Parameters​

  • runKey (string | string[]): The key or array of keys identifying the run(s) from which to retrieve variables.
  • variables (string[]): List of variable names to fetch.
  • optionals: Optional parameters.
    • timeout (number, optional): Timeout for the request in milliseconds.
    • ritual (keyof typeof RITUAL, optional): Execution ritual to apply. If EXORCISE is not explicitly set and multiple run keys are provided, it defaults to EXORCISE.
    • ignorable (boolean, optional): Whether the request can be safely ignored under certain conditions.
    • RoutingOptions = {} – Additional routing and request handling options.

Return value​

  • A promise that resolves to either:
    • A Record<string, unknown> mapping variable names to values (for a single run).
    • An array of records { runKey, variables } for each run when multiple runKeys are passed.

Usage example​

import { runAdapter } from 'epicenter-libs';

variableMap = await runAdapter.getVariables('0000019975d0aaebd160de2450566846su33', ['profit', 'sales']);

// or for multiple runs
variableSet = await runAdapter.getVariables(['0000019975d0aaebd160de2450566846su33', '0000019975d0logdi160de2450566846lu32'], ['profit', 'sales']);

Retrieve a run variable​

The getVariable() function retrieves a variable from a model run.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Sends a GET request to fetch the value of a specific variable from a run.
  • If multiple run keys or variables are provided, it delegates to getVariables() for batch retrieval.
  • Returns the value of the specified variable or the result of the batch call.
Function signature
export async function getVariable(
    runKey: string | string[],
    variable: string | string[],
    optionals: {
        timeout?: number,
        ritual?: keyof typeof RITUAL,
    } & RoutingOptions = {}
): Promise<unknown>

Parameters​

  • runKey (string | string[]): Key (or list of keys) for the run(s) to retrieve the variable(s) from.
  • variable (string | string[]): The name of the variable (or list of names) to retrieve.
  • optionals: Optional parameters to control the request.
    • timeout (number, optional): Number of seconds to wait for the response from the server.
    • ritual (keyof typeof RITUAL, optional): Optional ritual such as EXORCISE, SUMMON, etc.
    • RoutingOptions = {} – Additional routing and request handling options.

Return value​

A promise that resolves to:

  • The value of the variable (if both runKey and variable are strings).
  • A result from getVariables() if either runKey or variable is an array.

Usage example​

import { runAdapter } from 'epicenter-libs';

population = await runAdapter.getVariable('0000019975d0aaebd160de2450566846su33', 'population');

Update run variables​

The updateVariables() function updates model variables for one or more runs.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a PATCH request to the endpoint /run/variable/{runKey} or /run/variable if updating multiple runs.
  • Sends a dictionary of variable names and their new values to be updated within the specified run(s).
  • Returns the updated variables as a dictionary.
Function signature
export async function updateVariables(
    runKey: string | string[],
    update: Record<string, unknown>,
    optionals: {
        timeout?: number,
        ritual?: keyof typeof RITUAL,
    } & RoutingOptions = {}
): Promise<Record<string, unknown>>

Parameters​

  • runKey (string | string[]): A single run key or an array of run keys indicating which run(s) to update.
  • update (Record<string, unknown>): An object mapping variable names to their updated values.
  • optionals (Type: { timeout?: number, ritual?: keyof typeof RITUAL } & RoutingOptions = {}):
    • timeout (number, optional): Time in milliseconds before the request times out.
    • ritual (keyof typeof RITUAL, optional): Specifies the ritual to follow when updating. Non-EXORCISE rituals are not allowed with multiple run keys.
    • RoutingOptions = {} – Additional routing and request handling options.

Return value​

A promise that resolves to an object:

  • For a single run: A dictionary of variable names and their updated values.
  • For multiple runs: A dictionary keyed by runKey, each containing updated variable names and values.

Usage example​

import { runAdapter } from 'epicenter-libs';

await runAdapter.updateVariables('abc123', {
    userScore: 95,
    isActive: true
});

Operations​

Execute operation​

Use the operation() function to execute a named operation on a run.

Permissions​

Requires a role of ANONYMOUS or higher.

Function description​

  • Constructs a POST request to the /run/operation endpoint.
  • Provides the run key, operation name, and arguments.
  • Supplies optional arguments, including timeout and ritual.
  • Can target one or multiple runs, though certain rituals like EXORCISE must be used when calling across multiple runs.
Function signature
export async function operation(
    runKey: string | string[],
    name: string,           // Operation name
    args: unknown[] = [],   // Operation arguments
    optionals: {
        timeout?: number,
        ritual?: keyof typeof RITUAL,
    } & RoutingOptions = {}
): Promise<unknown>
Parameters​
  • runKey: string | string[] – The run identifier or a list of run identifiers the operation should be applied to.
  • name: string – The name of the operation to execute inside the model run.
  • args: unknown[] = [] – (Optional) Arguments to pass to the operation.
  • optionals – (Optional) Additional routing and execution control options:
    • timeout?: number – (Optional) Maximum duration (in ms) to wait for a response.
    • ritual?: keyof typeof RITUAL – (Optional) The ritual that determines how the run is revived or restored from memory/archive.
    • RoutingOptions – Additional routing and request handling options.
Return value​

A promise resolving to the result of the executed operation.

Usage example​
import { runAdapter, RITUAL } from 'epicenter-libs';

const result = await runAdapter.operation(
    '0000019975d0kdvso160de2450566846kr45',
    'calculatePrice',
    [42, 'premium'],
    { ritual: RITUAL.REANIMATE, timeout: 5000 }
);

console.log(result);

Trigger actions​

Permissions​

Requires a role of ANONYMOUS or higher.

Function description​

The action() function:

  • Constructs a POST request to the endpoint /run/action.
  • Executes one or more model-defined actions on a given run or array of runs.
  • Supports rituals, timeout, and flexible routing.
  • Returns a map of run keys to their resulting variable states.
Function signature
export async function action(
    runKey: string | string[],
    actionList: Action[],
    optionals: {
        timeout?: number,
        ritual?: keyof typeof RITUAL,
    } & RoutingOptions = {}
): Promise<Record<string, unknown>>

Parameters​

  • runKey (string | string[]): The key (or array of keys) identifying the run(s) on which to perform the actions.
  • actionList (Action[]): An array of actions to trigger. Each action can be a string (action name) or an object with name and optional params.
  • optionals:
    • timeout (number, optional): Number of seconds to wait for the response from the server.
    • ritual (keyof typeof RITUAL, optional): Ritual to apply when invoking the action.
    • RoutingOptions = {}: Additional routing options.

Return value​

A promise that resolves to a Record<string, unknown>:

  • If multiple run keys are used, each key maps to its respective output.
  • If a single run key is used, the resulting output for that run is returned.

Usage example​

import { runAdapter } from 'epicenter-libs';

await runAdapter.action('abc123', [
    { name: 'startSimulation' },
    { name: 'updateState', params: ["x", 42] }
]);

Metadata​

Get run metadata​

The getMetadata() function retrieves metadata for one or more runs.

Note

The function uses a POST request rather than GET.

Permissions​

Requires a role of ANONYMOUS or higher.

Function description​

  • Sends a POST request to the /run/meta endpoint.
  • Accepts a single runKey or multiple runKey values.
  • Converts the requested metadata keys into the request include parameter (semicolon-delimited).
  • Returns metadata values for a single run or an array of { runKey, data } results when multiple runs are requested.
Function signature
export async function getMetadata<M extends object = RunMetadata>(
    runKey: string | string[],
    metadata: (keyof M)[],
    optionals: {
        timeout?: number
    } & RoutingOptions = {}
): Promise<Pick<M, keyof M> | { runKey: string; data: Pick<M, keyof M> }[]>

Parameters​

  • runKey (string | string[]): A single run key or array of run keys for which metadata is requested.
  • metadata ((keyof M)[]): List of metadata keys to retrieve (typed to the generic metadata shape M).
  • optionals (Type: { timeout?: number } & RoutingOptions):
    • timeout? (number): Number of seconds to wait for the response from the server.
    • RoutingOptions: Additional routing options (e.g., network/call overrides).

Return value​

A promise that resolves to one of the following:

  • If runKey is a single string: an object containing the requested metadata key-value pairs.
  • If runKey is an array: an array of objects with the shape { runKey: string, data: Pick<M, keyof M> }.

Usage example​

import { runAdapter } from 'epicenter-libs';

// Single run
const meta = await runAdapter.getMetadata(
                            '00000173078afb05b4ae4c726637167s6t7u',
                            ['version', 'owner']);

// Multiple runs
const metaArray = await runAdapter.getMetadata(
                            ['00000173078afb05b4ae4c726637167s6t7u', '0000017dd3bf540e5ada5b1e058f08f36749',],
                            ['version', 'owner']);

Update run metadata​

The updateMetadata() function updates metadata for one or more runs.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Sends a PATCH request to the /run/meta endpoint.
  • Uses PATCH /run/meta/{RUN_KEY} when updating a single run.
  • Uses PATCH /run/meta when updating multiple runs.
  • Supports setting, pushing, and popping metadata values.
  • Returns the updated metadata values.
Function signature
export async function updateMetadata<M extends object = RunMetadata>(
    runKey: string | string[],
    update: MetadataUpdate<M>,
    optionals: {
        timeout?: number;
    } & RoutingOptions = {},
): Promise<Partial<M>>

Parameters​

  • runKey (string | string[]): Identifier for your run or runs.
  • update (MetadataUpdate<M>): Metadata update operations.
    • set? (Partial<M>): Key-value pairs to set in the metadata.
    • push? (Partial<Record<keyof M, unknown>>): Key-value pairs to push to array metadata.
    • pop? (Partial<Record<keyof M, { objectType: 'first' | 'last' | 'all' }>>): Keys with pop operations (first, last, or all) to remove values from array metadata.
  • optionals (Type: { timeout?: number } & RoutingOptions):
    • timeout? (number): Number of seconds to wait for the response from the server.
    • RoutingOptions: Additional routing options.

Return value​

A promise that resolves to an object containing the updated metadata key-value pairs.

Usage example​

import { runAdapter } from 'epicenter-libs';

// Set metadata values
const updated = await runAdapter.updateMetadata('00000173078afb05b4ae4c726637167s6t7u', {
    set: {
        classification: 'new-classification',
        categorization: 'new-categorization',
    },
});

// Push values to array metadata
const pushed = await runAdapter.updateMetadata('00000173078afb05b4ae4c726637167s6t7u', {
    push: {
        history: 'new-entry',
    },
});

// Pop values from array metadata
const popped = await runAdapter.updateMetadata('00000173078afb05b4ae4c726637167s6t7u', {
    pop: {
        history: { objectType: 'last' },
    },
});

Introspect​

The introspect functions return metadata for a model or for a specific model run.

Introspect model​

Use the introspect() function to retrieve metadata about a specific model.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Sends a GET request to introspect a model, providing the model file name as a path parameter.
  • Returns the API response in a Result object.
Function signature
export async function introspect(
    model: string,
    optionals: RoutingOptions = {}
): Promise<Record<string, unknown>>
Parameters​
  • model: string – The name or path of the model file to introspect.
  • optionals: RoutingOptions = {} – (Optional) Additional routing and request handling options. See RoutingOptions for details.
Return value​

A promise resolving to a Record<string, unknown> containing the introspected metadata associated with the given model file.

Usage example​
import { runAdapter } from 'epicenter-libs';

const modelInfo = await runAdapter.introspect('pricing-model.py');

console.log(modelInfo);

Introspect run​

Use the introspectWithRunKey() function to retrieve metadata for a specific model run.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Sends a GET request to introspect a run, providing a runKey as a path parameter.
  • Returns the API response in a Result object.
Function signature
export async function introspectWithRunKey(
    runKey: string,
    optionals: RoutingOptions = {}
): Promise<Record<string, unknown>>
Parameters​
  • runKey: string – The unique identifier for the run to be introspected.
  • optionals: RoutingOptions = {} – (Optional) Additional routing and request handling options. See RoutingOptions for details.
Return value​

A promise resolving to a Record<string, unknown> containing the introspected model metadata associated with the given run.

Usage example​
import { runAdapter } from 'epicenter-libs';

const modelInfo = await runAdapter.introspectWithRunKey('abc123');
console.log(modelInfo);